home *** CD-ROM | disk | FTP | other *** search
/ Programming Languages Suite / ProgramD2.iso / Borland / Borland Pascal with Objects 7.0 / RWDOC.ZIP / CUSTCNTL.RW < prev    next >
Text File  |  1992-10-27  |  18KB  |  443 lines
  1.                            CUSTCNTL.RW
  2.                            ===========
  3.  
  4.  
  5. 1        Creating custom control classes
  6. ----------------------------------------
  7.  
  8. Windows provides standard control classes, such as list boxes and
  9. radio buttons, that you can add to your dialog box resources. In
  10. addition to these standard classes, Resource Workshop also lets
  11. you create and use custom control classes. This file describes
  12. the functions you'll need to use to make your custom controls
  13. accessible to Resource Workshop.
  14.  
  15. See Chapter 4 in the Resource Workshop User's guide for
  16. descriptions of the standard menu controls and of how to load and
  17. use a custom control library.
  18.  
  19. You must store your custom controls in a dynamic-link library
  20. (DLL) file. For an example of how to use the custom control
  21. application program interface described in this file and to
  22. create a sample DLL file, see the BITBTN demonstration programs
  23. on your Resource Workshop distribution disks.
  24.  
  25. The DLL file must contain functions that enable Resource Workshop
  26. to work with the custom controls just as it works with the
  27. standard Windows controls. In particular, you must implement the
  28. ListClasses function and export it by name. This function
  29. provides information to Resource Workshop about the custom
  30. control classes in the DLL.
  31.  
  32. You must also provide the following functions for each custom
  33. control window class:
  34.  
  35. - Info
  36. - Style
  37. - Flags
  38.  
  39. These functions can have any name. They must, however, be
  40. exported by the DLL, and pointers to them must be supplied in the
  41. ListClasses function.
  42.  
  43.  
  44. 1.1      ListClasses function
  45. -----------------------------
  46.  
  47. ListClasses is a programmer-implemented function that passes
  48. information about the custom control classes back to Resource
  49. Workshop. Exporting ListClasses marks your DLL as supporting this
  50. custom control specification.
  51.  
  52. If ListClasses is present in the DLL, Resource Workshop calls the
  53. function, passing information about itself along with two utility
  54. function variables used in editing the custom control.
  55.  
  56. ListClasses should return a handle to global memory allocated by
  57. calling GlobalAlloc.  The memory referenced by this handle holds
  58. a record of type TCtlClassList, which describes the controls in
  59. the library.  TCtlClassList is described later in this section.
  60. The handle is freed by Resource Workshop and should not be freed
  61. by the DLL.
  62.  
  63. Syntax:
  64.  
  65.     function ListClasses(AppName: PChar; Version: Word;
  66.       Load: TLoad; Edit: TEdit): THandle; export;
  67.  
  68. Return value:
  69.  
  70.     Returns a handle to global memory containing a record of type
  71.     TCtlClassList.
  72.  
  73. Parameters:
  74.  
  75.     AppName        The class name of the main window of the
  76.                    calling application.  This value can be used
  77.                    by the custom control to determine if it is
  78.                    running under a resource editor. If AppName is
  79.                    'rwswnd', the calling application is Resource
  80.                    Workshop.
  81.  
  82.     Version        The version number of the calling application.
  83.                    The major version is in the high-order byte
  84.                    and the minor version in the low-order byte.
  85.                    For example, version 1.02 is $0102.
  86.  
  87.     Load           A function variable that custom controls can
  88.                    use to obtain the handle of a resource in the
  89.                    project being edited by the calling
  90.                    application (the equivalent of the Windows API
  91.                    function LoadResource). The function takes two
  92.                    parameters, a resource type name and a
  93.                    resource name. The custom control is
  94.                    responsible for freeing the global handle (if
  95.                    any) returned by this function.
  96.  
  97.     Edit           A function variable that custom controls can
  98.                    use to start a resource editor for any
  99.                    resource in the project being edited by
  100.                    Resource Workshop. The function takes two
  101.                    parameters, a resource type name and a
  102.                    resource name.
  103.  
  104. Return value records:
  105.  
  106.     PCtlClassList = ^TCtlClassList;
  107.     TCtlClassList = record
  108.       nClasses: Integer;           { Number of classes in list }
  109.       Classes: array[0..0] of TRWCtlClass;     { Class list }
  110.     end;
  111.  
  112.     TCtlClassList contains a variable number of TRWCtlClass
  113.     records, the number of which is determined by the nClasses
  114.     field.
  115.  
  116.     PRWCtlClass = ^TRWCtlClass;
  117.     TRWCtlClass = record
  118.       fnInfo:  TFnInfo;                       { Info function }
  119.       fnStyle: TFnStyle;                      { Style function }
  120.       fnFlags: TFnFlags;                      { Flags function }
  121.       szClass: array[0..ctlClass-1] of Char;  { Class name }
  122.     end;
  123.  
  124.     Each control class in the DLL must have a corresponding
  125.     TRWCtlClass record in the TCtlClassList. The szClass field
  126.     contains the name with which the class was registered. For
  127.     example, if you called RegisterClass giving the class name as
  128.     'MYBUTTON', szClass must be 'MYBUTTON'.
  129.  
  130. The function variables Info, Style, and Flags--which correspond
  131. to the pointers TFnInfo, TFnStyle, and TFnFlags--are described in
  132. the following sections.
  133.  
  134.  
  135. 1.2      Info function
  136. ----------------------
  137.  
  138. The Info function is called by Resource Workshop to retrieve
  139. information about the control class, including the string to add
  140. to the control menu and the bitmap to add to the tool palette.
  141. The function returns a memory handle that can be allocated by
  142. GlobalAlloc. This handle must refer to memory that contains a
  143. TRWCtlInfo record.  Like ListClasses, the handle returned by Info
  144. is freed by Resource Workshop and should not be freed by the DLL.
  145. This function is called once by Resource Workshop upon loading
  146. the DLL.
  147.  
  148. Syntax:
  149.  
  150.     function Info: Handle; export;
  151.  
  152. Return value:
  153.  
  154.     Returns a handle to global memory containing a record of type
  155.     TRWCtlInfo.
  156.  
  157. Parameters:
  158.  
  159.     None.
  160.  
  161. Return value record:
  162.  
  163.     TRWCtlInfo has two parts:
  164.  
  165.     - A fixed-length part that provides information about the
  166.       control class in general.
  167.  
  168.     - A variable-length array of records, with each record
  169.       providing information about a particular type or subclass
  170.       of the control.
  171.  
  172.     Each control class can include several control types. For
  173.     example, Windows provides a BUTTON class that includes push
  174.     buttons, radio buttons, and check boxes. This variety can be
  175.     duplicated by your classes by providing two or more
  176.     TRWCtlType records in the TRWCtlInfo record.
  177.  
  178.     The following is the declaration of TRWCtlInfo:
  179.  
  180.     PRWCtlInfo = ^TRWCtlInfo;
  181.     TRWCtlInfo = record
  182.       wVersion:   Word;           { control version }
  183.       wCtlTypes:  Word;           { control types }
  184.       szClass:    array[0..ctlClass-1] of Char;
  185.                                   { control class name }
  186.       szTitle:    array[0..ctlTitle-1] of Char;
  187.                                   { control title }
  188.       szReserved: array[0..9] of Char;
  189.                                   { reserved for future use }
  190.       ctType:     array[0..ctlTypes] of TRWCtlType;
  191.                                   { control type list }
  192.     end;
  193.  
  194.     wVersion       The version number of the custom control
  195.                    library. The major version is in the
  196.                    high-order byte and the minor version in the
  197.                    low-order byte. For example, version 1.02 is
  198.                    $0102. This field is not used by Resource
  199.                    Workshop.
  200.  
  201.     wCtlTypes      The number of control sub-types defined in the
  202.                    ctType array.
  203.  
  204.     szClass        The name of the class as registered with
  205.                    Windows.  This is duplicated from the
  206.                    TCtlClassList record to retain upward
  207.                    compatiblity with the Windows custom control
  208.                    specificiation.
  209.  
  210.     szReserved     Space reserved for future expansion.  Must be
  211.                    cleared to null characters (#0).
  212.  
  213.     ctType         An array of sub-type description records of
  214.                    type TRWCtlType.
  215.  
  216.     The following is the declaration of TRWCtlType:
  217.  
  218.     PRWCtlType = ^TRWCtlType;
  219.     TRWCtlType = record
  220.       wType:   Word;                         { type style }
  221.       wWidth:  Word;                         { suggested width }
  222.       wHeight: Word;                         { suggested height }
  223.       dwStyle: LongInt;                      { default style }
  224.       szDescr: array[0..ctlDescr-1] of Char; { menu name }
  225.       hToolBit:  HBitmap;                    { toolbox bitmap }
  226.       hDropCurs: HCursor;              { drag and drop cursor }
  227.     end;
  228.  
  229.     wType          A user-defined value used to indicate the
  230.                    sub-type of the control.  This value is not
  231.                    used by Resource Workshop.
  232.  
  233.     wWidth         The default width for the control.  Resource
  234.                    Workshop will use this value if, for example,
  235.                    the control is created by dragging the icon
  236.                    from the tool palette.  wWidth is in dialog
  237.                    coordinates unless the most significant bit is
  238.                    set, in which case the value is in pixels. For
  239.                    example, a value of "32" is 32 in dialog
  240.                    coordinates, but the value "32 or $8000" is in
  241.                    pixels.
  242.  
  243.     wHeight        The default height for the control.  Resource
  244.                    Workshop will use this value if, for example,
  245.                    the control is created by dragging the icon
  246.                    from the tool palette.  wHeight is in dialog
  247.                    coordinates unless the most significant bit is
  248.                    set, in which case the value is in pixels. For
  249.                    example, a value of "32" is 32 in dialog
  250.                    coordinates, but the value "32 or $8000" is in
  251.                    pixels.
  252.  
  253.     wStyle         The default style Resource Workshop will use
  254.                    to create the Window.  This is the key field
  255.                    that you will use to distinguish one subtype
  256.                    from another.
  257.  
  258.     szDescr        The description of the control subtype.  This
  259.                    text is used by Resource Workshop to construct
  260.                    a menu item that the user can use to create an
  261.                    instance of your custom control.
  262.  
  263.     hToolBit       A handle to a bitmap which will be placed on
  264.                    the tool palette.  Resource Workshop requires
  265.                    the bitmap be a 22x22 black and gray bitmap
  266.                    containing a 2-pixel border that is white on
  267.                    the top and left and black on the bottom and
  268.                    right. You can use the bitmaps contained in
  269.                    BITBTN.RES as templates.
  270.  
  271.     hDropCurs      A cursor to be used while dragging the control
  272.                    from the tool palette.
  273.  
  274.  
  275. 1.3      Style function
  276. -----------------------
  277.  
  278. The Style function makes it possible for you to edit your custom
  279. control. You must first create an appropriate dialog box in
  280. Resource Workshop and then implement a Boolean function that
  281. displays that dialog box. Resource Workshop calls this function
  282. whenever you initiate a request to edit the custom control.
  283. Resource Workshop passes the function a handle to the window that
  284. is the parent of the dialog, a handle to memory containing the
  285. TRWCtlStyle record, and two function variables for string
  286. conversion.
  287.  
  288. Return value:
  289.  
  290.     The function must return true if the TRWCtlSytle record has
  291.     been modified; otherwise, it must return false.
  292.  
  293. Syntax:
  294.  
  295.     function Style(Window: HWnd; CtlStyle: THandle; StrToId:
  296.       TStrToId; IdToStr: TIdToStr): Bool; export;
  297.  
  298. Parameters:
  299.  
  300.     Window         A handle to the parent window of the dialog
  301.                    box displayed by this function.
  302.  
  303.     CtlStyle       A handle to global memory containing the
  304.                    TRWCtlStyle record to be edited.
  305.  
  306.     StrToId        A function variable that converts a string
  307.                    into a control ID for the wId field of
  308.                    TRWCtlStyle. This allows the user to enter the
  309.                    control ID using a constant identifier. This
  310.                    routine evaluates the string as an expression,
  311.                    returning the result.  The ID can be converted
  312.                    back into a string by calling IdToStr.
  313.  
  314.     IdToStr        A function variable that converts the control
  315.                    ID in the wId field of TRWCtlStyle to a string
  316.                    for editing. The ID can be converted back into
  317.                    a word by calling StrToId. This function
  318.                    variable allows the user to see the symbolic
  319.                    constant that represents the control ID
  320.                    instead of the word value.
  321.  
  322. CtlStyle record:
  323.  
  324.     The following is the record type referenced by the CtlStyle
  325.     memory handle:
  326.  
  327.     PRWCtlStyle = ^TRWCtlStyle;
  328.     TRWCtlStyle = record
  329.       wX:   Word;               { x origin of control }
  330.       wY:   Word;               { y origin of control }
  331.       wCx:  Word;               { width of control }
  332.       wCy:  Word;               { height of control }
  333.       wId:  Word;               { control child id }
  334.       dwStyle: LongInt;         { control style }
  335.       szClass: array[0..ctlClass-1] of Char;
  336.                                 { name of control class }
  337.       szTitle: array[0..ctlTitle-1] of Char;
  338.                                 { control text }
  339.       CtlDataSize: Byte;        { control data size }
  340.       CtlData: array[0..ctlDataLength-1] of Char;
  341.                                 { control data }
  342.     end;
  343.  
  344.       wX           The horizontal (X) location of the control in
  345.                    dialog coordinates.
  346.  
  347.       wY           The vertical (Y) location of the control in
  348.                    dialog coordinates.
  349.  
  350.       wCx          The width of the control in dialog
  351.                    coordinates.
  352.  
  353.       wCy          The height of the control in dialog
  354.                    coordinates.
  355.  
  356.       wId          The control's ID value.  This value must be
  357.                    converted to a string by calling IdToStr
  358.                    before being displayed for editing. It must be
  359.                    converted back into a word for storage by
  360.                    calling StrToId after editing.
  361.  
  362.       dwStyle      The style flags of the control.
  363.  
  364.       szClass      The class name of the control.
  365.  
  366.       szTitle      The title of the control.
  367.  
  368.       CtlDataSize  Windows allows controls in a resource file to
  369.                    have up to 255 bytes of control-defined data.
  370.                    This field indicates how much of that space is
  371.                    being used by the control.  The data is stored
  372.                    in CtlData.
  373.  
  374.       CtlData      This field holds up to 255 bytes of
  375.                    control-specific data.  The amount used must
  376.                    be recorded in the CtlDataSize field.  The use
  377.                    of this data area is user-defined.
  378.  
  379. When you save your project, Resource Workshop saves the CtlData
  380. array into the .RC or .RES file.
  381.  
  382. To enable a custom control to access this array from within your
  383. program at run time, lParam of the WM_CREATE message points to a
  384. CREATESTRUCT data structure. The CREATESTRUCT structure contains
  385. a field, lpCreateParams, that is a pointer to the extra data you
  386. stored in the CtlData array. If the pointer is nil, there is no
  387. CtlData.
  388.  
  389. The CtlDataSize variable is not available to your program. To
  390. make the size data accessible to your program, the CtlData array
  391. should either contain a fixed amount of data, or its first byte
  392. should contain the length of the data.
  393.  
  394. The Style function first converts the ID to a string by passing
  395. the numerical ID value to IdToStr. The Style function then
  396. displays the string in the dialog box.
  397.  
  398. If the user changes the string that's returned by IdToStr, the
  399. Style function verifies the string by passing it to StrToId,
  400. which determines if the string is a valid constant expression. If
  401. StrToId returns a zero in the low word, the ID is illegal and is
  402. displayed in the dialog box so the user can change it to a valid
  403. ID. If StrToId is successful, it returns a nonzero value in the
  404. low word and the ID in the high word.
  405.  
  406.  
  407. 1.4      Flags function
  408. -----------------------
  409.  
  410. The Flags function is used by Resource Workshop to translate the
  411. style of a control into text.  Resource Workshop inserts the text
  412. into the .RC file being edited.  The function must only convert
  413. the values unique to the control.  For example, if you were
  414. creating a Flags function for the Windows button class, you would
  415. only examine the lower sixteen bits of Flags and translate them
  416. into one of the bs_XXXX constants.
  417.  
  418. Return value:
  419.  
  420.     Returns the number of bytes copied into the destination
  421.     string. Returns 0 if the Flags word is not valid or the
  422.     string exceeds MaxString in length.
  423.  
  424. Syntax:
  425.  
  426.     function Flags(Flags: LongInt; Style: PChar; MaxString:
  427.       Word): Word;
  428.  
  429.   Parameters:
  430.  
  431.     Flags          The style of the control to be translated into
  432.                    text.  This field is derived from the dwStyle
  433.                    field of the TRWCtlStyle record passed to the
  434.                    Style function variable.
  435.  
  436.     Style          The location to write the translated text.
  437.  
  438.     MaxString      The maximum number of bytes the Flags function
  439.                    can write into Style.
  440.  
  441.  
  442.            ========= END OF FILE CUSTCNTL.RW =========
  443.